#pragma once
// ArrayChar.h
// 作者：MetaQuotes Ltd.（整理）
// 说明：char 类型动态数组 CArrayChar 接口声明，带详细中文注释

#include "Array.mqh"

/**
 * @brief char 类型的动态数组类
 * 
 * 功能：
 *  - 提供 char 类型数组的增删、访问、排序等操作
 *  - 支持数组与文件的保存与加载
 *  - 支持排序数组的快速插入和搜索
 * 
 * 继承自：
 *  - CArray
 */
class CArrayChar : public CArray
{
protected:
    char m_data[];  ///< char 类型数组数据

public:
    /**
     * @brief 构造函数
     */
    CArrayChar(void);

    /**
     * @brief 析构函数
     */
    ~CArrayChar(void);

    //--- 对象类型标识方法
    /**
     * @brief 获取对象类型
     * @return 类型标识码 TYPE_CHAR
     */
    virtual int Type(void) const { return TYPE_CHAR; }

    //--- 文件操作方法
    virtual bool Save(const int file_handle);  ///< 保存数组到文件
    virtual bool Load(const int file_handle);  ///< 从文件加载数组

    //--- 动态内存管理方法
    bool Reserve(const int size);  ///< 为数组预留指定数量空间
    bool Resize(const int size);   ///< 调整数组大小
    bool Shutdown(void);           ///< 清空数组并释放内存

    //--- 填充数组方法
    bool Add(const char element);                     ///< 在数组末尾添加元素
    bool AddArray(const char &src[]);                ///< 添加另一个 char 数组
    bool AddArray(const CArrayChar *src);           ///< 添加另一个 CArrayChar 对象
    bool Insert(const char element, const int pos); ///< 在指定位置插入元素
    bool InsertArray(const char &src[], const int pos); ///< 在指定位置插入数组
    bool InsertArray(const CArrayChar *src, const int pos); ///< 在指定位置插入 CArrayChar 对象
    bool AssignArray(const char &src[]);            ///< 赋值另一个数组（复制）
    bool AssignArray(const CArrayChar *src);        ///< 赋值另一个 CArrayChar 对象（复制）

    //--- 访问数组方法
    char At(const int index) const;                  ///< 获取指定索引元素
    char operator[](const int index) const { return At(index); } ///< 索引操作符访问元素

    //--- 查找最小值和最大值方法
    int Minimum(const int start, const int count) const { return CArray::Minimum(m_data, start, count); }
    int Maximum(const int start, const int count) const { return CArray::Maximum(m_data, start, count); }

    //--- 修改数组元素方法
    bool Update(const int index, const char element); ///< 更新指定索引元素
    bool Shift(const int index, const int shift);     ///< 将元素移动指定偏移量

    //--- 删除元素方法
    bool Delete(const int index);                     ///< 删除指定索引元素
    bool DeleteRange(int from, int to);              ///< 删除指定范围元素

    //--- 数组比较方法
    bool CompareArray(const char &array[]) const;   ///< 比较数组内容是否相等
    bool CompareArray(const CArrayChar *array) const; ///< 比较 CArrayChar 对象内容是否相等

    //--- 排序数组相关方法
    bool InsertSort(const char element);            ///< 向已排序数组插入元素
    int Search(const char element) const;           ///< 查找元素在排序数组中的位置
    int SearchGreat(const char element) const;      ///< 查找第一个大于指定元素的位置
    int SearchLess(const char element) const;       ///< 查找第一个小于指定元素的位置
    int SearchGreatOrEqual(const char element) const; ///< 查找第一个大于等于指定元素的位置
    int SearchLessOrEqual(const char element) const;  ///< 查找第一个小于等于指定元素的位置
    int SearchFirst(const char element) const;      ///< 查找元素第一次出现的位置
    int SearchLast(const char element) const;       ///< 查找元素最后一次出现的位置
    int SearchLinear(const char element) const;     ///< 线性搜索元素位置

protected:
    virtual void QuickSort(int beg, int end, const int mode=0); ///< 快速排序
    int QuickSearch(const char element) const;                  ///< 快速查找元素位置（用于排序数组）
    int MemMove(const int dest, const int src, int count);      ///< 数组内部元素移动
};
